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HP 98550A Software Portability Note 


Introduction 

The Starbase graphics library is Hewlett-Packard’s programming library for access to 
HP graphics devices. A feature of this library is a set of procedures to do graphics 
transformations and output primitives using floating-point world coordinates. A current 
development effort at Technical Workstation Operation is to design and implement a 
corresponding set of integer world coordinate procedures, called the integer interface. 
This interface is intended to meet the needs of many 2-D applications in Electrical En¬ 
gineering and some other CAD areas where coordinate data is naturally integer-based. 
This interface will not provide 3-D functionality. 

This document is intended to provide an overview of the integer interface and aid in 
porting or writing applications to use it. The integer interface will be supported by 
an accelerator. This accelerator will enhance graphics performance on the HP 98550A 
display (as well as compatible displays that support the accelerator.) The interface will 
also be supported by Starbase for displays that do not have appropriate accelerator 
hardware. 

Good graphics programming practices should be followed in any application that is 
expected to be portable to new devices and new display resolutions. Some of these 
practices are described in the chapters entitled “Device-independent Programming and 
Performance Enhancement” in the Graphics Techniques HP-UX Concepts and Tutorials 
manual. Other chapters in that manual describe basic graphics terminology and concepts 
not explained in this document. 


Note 

The procedure descriptions and other details of the integer inter¬ 
face shown in this document are subject to change. While most 
changes are expected to be minor, Hewlett-Packard reserves the 
right to alter any specification before final release. 
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Interface Overview 

Integer interface is selected by placing the INT.XFORM flag in the gopen mode param¬ 
eter. The default mode, INT.XFORM absent, is the floating-point interface. 

The integer interface accepts coordinate data in 32-bit integer format. Internally, com¬ 
putations are done with 64-bit precision, and the results adjusted to 32 bits. Integer 
and floating-point calls cannot be mixed; if INT.XFORM is present, floating point calls 
are flagged as errors; if INT.XFORM is absent, integer calls are errors. The procedures 
appropriate for each interface are discussed later. 

Transformation Pipelines 

The integer interface provides either of two transformation pipelines. An integer transfor¬ 
mation matrix stack is provided, similar to the floating-point matrix stack. The integer 
interface matrix representation differs from the floating-point matrix representation and 
is described later. 

If MODEL_XFORM is present in the gopen mode parameter, user objects described in 
modeling coordinates can be individually rotated, scaled, and translated by a modeling 
transform as they are converted to world coordinates. World coordinates are in turn 
converted to virtual device coordinates by a viewing transform, and finally to device 
coordinates by the vdc-to-dc transform. The latter two stages are usually combined into 
a single viewing transformation. This architecture is useful when objects in a data base 
are to be manipulated and moved independently of each other. 

If MODEL_XFORM is absent from the gopen mode parameter, separate control of the 
modeling and viewing transforms is not possible. Starbase recomputes a single transfor¬ 
mation matrix whenever any part of the pipeline is changed. This architecture is slightly 
more efficient when elements of the data base do not need to be transformed in relation 
to each other, and when all the data must be quickly redrawn. 

Since 3-D procedures are not provided in the integer interface, operations such as per¬ 
spective divide or hither-yon clipping are not part of the integer pipeline. 
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Matrix Representation 

Computations with 2-D transformations are done internally using 3x3 matrices. The 
integer interface defines matrix parameters as 3x2 integer arrays. The third column of 
each matrix can be assumed because it is always: 

' 0 " 

0 

1 

Scaling and translation are transformations easily represented by matrices with integer 
elements. Rotation depends on the sine and cosine functions and requires fractions to 
allow rotations that are not multiples of 90°. 

In the Starbase integer interface, a fraction is represented as an integer mantissa multi¬ 
plied by 2 raised to a negative power. The exponent is called the radix, and is expressed 
as a positive integer in the range 0 through 32. Each integer matrix has an associated 
radix value. Normally the radix is considered to apply to all elements of the matrix. 
However, if the raw parameter is set to TRUE in the matrix procedure call, the radix 
adjustment applies only to the rotation elements. This format allows the maximum range 
for translation while keeping good accuracy in rotation and scaling, and is used internally 
by Starbase. The rotation elements are mat[0][0], mat[0][l], mat[l][0], and mat[l][l]. The 
elements mat[2][0] and mat[2][l] are used for translation. 

Converting a floating-point value to radix format can be done easily (the radix value 
being predetermined): 

int_value = (int) (float_value * (1 « radix)); 

Conversely, to extract a floating point value from a radix representation: 

float.value = ((float) int_value)/((float)(1 « radix)); 

The radix value can be thought of as the number of bits to the right of the binary point in 
the equivalent floating point arithmetic. When matrices are multiplied, the radix values 
must be added together. If the sum overflows the maximum value of 32, precision is lost 
as the matrix elements are adjusted to reduce the radix. This should only happen when 
several rotation and scaling matrices are concatenated, or when unusually high precision 
is specified. 

Large integer values leave few bits remaining for fractional precision. 
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Procedure Descriptions 

The integer interface procedures can be grouped into several categories: 

• Output Primitives 

• Primitive Attributes 

• Transform Operations 

• Input and Inquiry Routines 

• Miscellaneous Other Routines 

• Changes to Existing Routines 

Each of these groups will be discussed below. Most changes simply substitute integer 
world coordinate parameters for the floating-point parameters in the equivalent Starbase 
procedures. You should consult the Starbase Reference manual to understand these 
changes. Only significant differences from existing routines will be discussed in the 
following sections. 

The names of all procedures requiring integer world coordinate data or matrix parameters 
have been prefixed with int to distinguish them from floating-point and device-coordinate 
analogs. 
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Integer Interface Output Primitives 

void intarc(fildes,radius,x.center,y_center,start,stop,close.type); 
int fildes,radius,x_center,y_center,close_type; 
float start.stop; 

void intpartial_arc(fildes,radius,x_center,y_center,start,stop,close_type, 
closure); 

int fildes,radius,x_center,y_center,close_type,closure; 
float start,stop; 

void intcircle(fildes.radius,x_center,y_center); 
int fildes,radius,x_center,y_center; 

void intpartial_circle(fildes,radius,x_center,y_center,closure); 
int fildes,radius,x_center,y.center,closure; 

void intdraw2d(filde8,x,y); 
int fildes,x,y; 

void intmove2d(fildes,x,y); 
int fildes.x.y; 

void intpartial_polygon2d(fildes,clist.numverts,flags,closure); 
int fildes.numverts.flags,closure; 
int clist [] ; 

void intpolygon2d(filde8 l cli8t,numvert8,flag8); 
int fildes,numverts,flags; 
int clist [] ; 

void intpolyline2d(filde8,cli8t.numpts,flags); 
int fildes.numpts.flags; 
int clist [] ; 

void intpolymarker2d(fildes,clist.numpts,flags); 
int fildes.numpts.flags; 
int clist [] ; 

void intrectangle(fildes,xl,yl,x2,y2); 
int fildes.xl.yl,x2,y2; 
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void inttext2d(fildes,x,y,8tring,xform); 
int fildes.x.y.xform; 
char *8tring; 

Characters are drawn using the default text alignment for the current text path: 


Path 

Normal 

Horizontal 

Normal 

Vertical 

right 

left 

baseline 

left 

right 

baseline 

up 

center 

baseline 

down 

center 

top 


Only fonts 1 and 2 (see textJont_index(3g)) work correctly; others may not draw complete 
characters. All control characters in the string are ignored (except for space, octal 40). 

Integer Interface Primitive Attributes 

void intcharacter_height(fildes.height); 
int fildes,height; 

void intcharacter_width(fildes.width); 
int fildes.width; 

void intline_repeat_length(fildes,length); 
int fildes,length; 

void intmarker_8ize(fildes,size.mode); 
int fildes,size.mode; 

void intperimeter_repeat_length(fildes,length); 
int fildes,length; 

void inttext_orientation2d(fildes,up_x,up_y,base_x,base_y); 
int fildes,up_x,up_y,base_x.base_y; 
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Integer Interface Transform Operations 

void intclip_rectangle(fildes,lower_left_x,upper_right_x,lower_left_y, 
upper_right_y); 

int fildes,lower_left_x,upper_right_x,lower.left_y,upper_right_y; 

Defaults: 

(lower_left_x,upper_right_x,lower.left_y,upper_right_y) = (0,32767,0,32767) 

void intconcat_matrix2d(matrixl,matrix2,result,radixl,radix2,radix,raw); 
int matrixl[3][2],matrix2[3][2].result[3] [2]; 
int radixl,radix2,*radix,raw; 

void intconcat^transformation2d(fildes.xform,radix,sequence,stack,raw); 
int fildes.radix,sequence,stack raw; 
int xform[3][2]; 

void intpop_matrix2d(fildes.xform,radix,raw); 
int fildes,*radix,raw; 
int xform[3] [2]; 

void intpush_matrix2d(fildes.xform,radix,raw); 
int fildes.radix,raw; 
int xform[3][2]; 

void intreplace_matrix2d(fildes.xform,radix,raw); 
int fildes.radix,raw; 
int xform[3][2]; 

void inttransform_point2d(fildes,mode,inx,iny,outx,outy); 
int fildes,mode,inx,iny,*outx,*outy; 

void intvdc_extent(fiIdes,xmin,ymin,xmax,ymax); 
int fildes,xmin,ymin,xmax,ymax; 

void intview_matrix2d(fildes.xform,radix,usage,raw); 
int fildes,radix,usage.raw; 
int xform[3][2]; 

void intview__port (fildes,xl, yl, x2, y2); 
int fildes,xl,yl,x2,y2; 

void intview_window(filde8,xl,yl,x2,y2); 
int fildes.xl,yl,x2,y2; 
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Integer Interface Input Routines and Inquiries 

void intinquire_text_extent2d(fildes,string,xform,extent); 
int fildes.xform,extent[8]; 
char *8tring; 

On return, the extent array contains: 


extent [0] 
extent [1] 
extent [2] 
extent [3] 
extent [4] 
extent [5] 
extent [6] 
extent [7] 


concatenation point (x coordinate) 
concatenation point (y coordinate) 
lower left corner (x coordinate) 
lower left corner (y coordinate) 
upper left corner (x coordinate) 
upper left corner (y coordinate) 
upper right corner (x coordinate) 
upper right corner (y coordinate) 


void intinq_pick.window(fildes,px_min,py_min,px_max,py_max); 
int fildes,*px_min,*py_min,*px_max,*py_max; 

void intrequest_locator2d(fildes.ordinal.timeout.valid,x.y); 
int fildes,ordinal,*valid,*x,*y; 
float timeout; 

void int8ample_locator2d(fildes,ordinal,valid,x,y); 
int fildes,ordinal,*valid,*x,*y; 

Miscellaneous Other Integer Interface Routines 

void file_to_intbitmap(fildes,full_depth,spn.dpn,source.xstart,ystart, 
update.cmap); 

int fildes,full.depth,spn.dpn; 
char * 80 urce; 
int xstart.ystart; 
int update.cmap; 

void intbitmap.print(fildes,formatter,config,print.mode,full,xstart,ystart, 
xlen.ylen,rotate,foreground,background,noback); 

int fildes; 

char ^formatter,*config; 
int print.mode,full; 
int xstart.ystart; 
int xlen.ylen; 

int rotate,foreground,background,noback; 
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void intbitmap_to_file(fildes,full.depth,spn,dpn,dest,xstart,ystart,xlen, 
ylen,store_cmap); 
int fildes,full_depth,8pn,dpn; 
char *dest; 
int xstart.ystart; 
int xlen.ylen; 
int store.cmap; 

void intblock_move(fildes,x_source,y_source length_x,length.y,x_dest,y_dest); 
int fildes,x.source.y.source.length.x.length.y.x.dest,y_dest); 

void intblock_read(fildes,x_source,y_source,length_x,length_y,pixel.data,raw); 
int fildes,x.source,y.source,length.x,length_y; 
unsigned char *pixel_data; 
int raw; 

void intblock_write(fildes,x_dest,y_dest,length_x,length_y, pixel.data,raw); 
int fildes,x_dest,y.dest,length.x,length.y; 
unsigned char *pixel_data; 
int raw; 

void intecho_type2d(filde8,echo_number l echo_value,x,y); 
int fildes,echo.number,echo.value,x,y; 

void intecho_update2d(filde8,echo_number,x,y); 
int filde8,echo_number,x,y; 

void int8et_pick_window(fildes,px_min,py_min,px_max,py_max); 
int fildes,px_min,py_min,px_max,py_max; 
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Changes to Existing Routines 

void curve.resolution(fildes,coordinate.type,u.interior,v_interior,u.exterior, 
v_exterior); 

int fildes.coordinate.type; 

float u_interior,v_interior,u_exterior,v.exterior; 

This procedure now affects curves generated by intarc, 
intpartial_arc,intcircle, and intpartial_circle. 

int gopen(path,kind,driver,mode); 
char *path,*driver; 
int kind.mode; 

This procedure now accepts the INT_XFORM flag indicating that integer 
transforms are to be used 

void set_hit_mode(fildes,hit_mode); 
int fildes,hit.mode; 

void inquire_hit(fildes,hit); 
int fildes,*hit; 

The picking aperture may now be set by intset_pick_window. Hits 
are registered for the integer interface output primitives listed above. 

void pop_matrix(fildes); 
int fildes; 

This procedure will pop a matrix off the integer matrix stack and discard 
it, just as in the floating point interface. 
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Programming with the Integer Interface 

The integer interface is still under development; obviously it is not available in any 
released version of the Starbase library. If yours is an application that will benefit from 
the integer world coordinates and the potential performance accelerator, it is possible 
to adapt your code now to the interface and minimize the code effort required when the 
revised Starbase library is released. 

The most modular approach to this problem is to implement a set of procedures that 
emulate the integer interface using the existing floating-point interface. If your data 
base is currently in integer format, your application is probably doing this now to use 
Starbase. This interface module can be linked into the application program until the 
Starbase library provides the defined procedures. 

Most of the routines that must be implemented are simple “onion-skin” procedures that 
convert integer parameters to floating-point. This can be done easily in the C language 
using the cast operation; library and intrinsic functions are available in Pascal and FOR¬ 
TRAN 77 to do the same functions. 

Here is a simple example of an onion skin procedure for intmarker_size: 

void intmarker.size (fildes,size.mode) 
int fildes.size.mode; 

{ 

marker.size (fildes,(float)size.mode); 

> 


A more complex example that shows the conversion of a matrix from integer to floating¬ 
point format is intpush_matrix2d: 

void intpush_matrix2d(fildes.xform,radix,raw) 
int fildes,xform[3][2].radix,raw; 

{ 

float fxform[3][2],dev; 


if (radix == 0) { 

/* this optimization for radix == 
is not absolutely necessary */ 


fxform[0] [0] 
fxform[0] [1] 
fxform[l] [0] 
fxformfl] [1] 
fxform[2][0] 
fxform[2] [1] 


xform[0][0] 
xform[0][1] 
xform[1][0] 
xform[l] [1] 
xform[2][0] 
xform [2] [1] 


0 
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else { 

/* the rotation elements must always be adjusted by the radix */ 
dev = l«radix; 


fxform[0] [0] = xform[0] [0]/dev; 

fxform[0] [1] = xform[0] [1]/dev; 

fxform[l] [0] = xform[l] [0]/dev; 

fxform[l] [1] = xform[l] [1]/dev; 

/* the translation elements are 
if (raw) { 

fxform[2] [0] = xform[2] [0] ; 
fxform[2] [1] = xform[2] [1] ; 

> 


else { 

fxform[2] [0] = xform[2] [0]/dev 
fxform[2][l] = xform[2] [l]/dev 


> 


adjusted if not raw format */ 


> 


pu8h_matrix2d(fildes.fxform); 

> 


The change to the gopen call can be made by defining a constant INT_XFORM as having 
value 0x20. However, postponing the change to the gopen call until the true integer 
interface is available may be just as easy as adding and then removing the constant 
definition. 

Emulation procedures for all the integer interface routines described above compile to a 
relocatable file that can be linked into any Starbase application (preceding -lsbl in the 
link sequence). If the code size is prohibitive, the procedures can be grouped into smaller 
relocatable modules collected into a library format by the ar(l) command. The linker 
can search such an archive and include only the needed relocatable files. 
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Programming Tips 

Here are some other general tips on programming for the integer interface and for the 
accelerator: 

1 . Use large VDC extents. Small integer ranges will amplify the error due to integer 
arithmetic. The floating-point default range (0.0 to 1.0) is not useful in the integer 
interface. 

2 . Use integer coordinates for all graphics data. As stated above, mixing floating¬ 
point and integer calls is not possible, and converting data from one format to the 
other is error-prone and slow. 

3 . If you would prefer to convert from float to integer data some of the time, it may 
be valuable to write macros to do the conversion, so that the conversion can be 
modified or removed later. 

4. Keep Starbase calls concentrated in a few files. This will make later modifications 
more localized. 

5 . Study the Starbase Graphics Techniques manual, especially the chapters about 
device-independent programming. Make sure all commitments to specific resolu¬ 
tions, numbers of planes, or other device features are made consciously. This is 
especially true of gescape operations that are not guaranteed to be supported in 
future drivers. 

6 . For raster operations, be aware of the effect of higher resolution devices that may 
be introduced in the future. Raster characters and menus will appear smaller on 
higher-resolution devices, unless care is taken to make the program adapt to the 
device resolution. 

7 . Follow performance hints provided in the driver chapters. These include advice 
about avoiding the alternation of attribute changes with output primitives, the 
relative costs of various drawing modes, and other driver-specific information. 

8 . Disjoint vectors should be placed into an array (with move/draw indicator if needed) 
and performed using the polyline procedures. Polylines are much more efficient than 
moves and draws. 

9. Rectangles drawn using the rectangle procedure are somewhat faster than if done 
as unrotated polygons. 

10. The accelerator is expected to provide hardware support for circles drawn with 
intcircle. Calls to intarc, intpartial.arc, and intpartial.circle will not perform 
as well, because the accelerator will not support them. 
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11. The accelerator will perform faster on non-overlapped windows than on overlapped 
windows. 


Starbase Procedures and Coordinate Systems 

Some Starbase procedures are only used with a single coordinate system, and some are 
common to more than one. A list of Starbase procedures and their related coordinate 
systems are shown below. 


Floating Point Only 

append.text 

bitmap_to_file 

block.read 

character.width 

concat.matrix 

dc_to_vdc 

depth_cue 

draw3d 

ellipse 

inquire.pick.depth 

light.ambient 

light.switch 

marker.size 

partial.arc 

partial_polygon3d 

polygon3d 

polymarker2d 

pop_matrix3d 

readjocator.event 

replace_matrix3d 

setjocator 

shade.mode 


arc 

bitmap.print 

block.write 

clip.depth 

concat_transformation2d 

default_knots 

depthjndicator 

echo.type 

file.to.bitmap 

inquire_pick_window 

light.model 

line_repeat_length 

move2d 

partiaLellipse 

perimeter_repeat_length 

polyline2d 

polymarker3d 

push_matrix2d 

rectangle 

request_locator 

set_pick_depth 

shade.range 


backface.control 

block.move 

character.height 

clip.rectangle 

concat_transformation3d 

define_trimming_curve 

draw2d 

echo.update 

hidden.surface 

inquire_text_extent 

light.source 

marker_orientation 

move3d 

partial_polygon2d 

polygon2d 

polyline3d 

pop_matrix2d 

push_matrix3d 

replace_matrix2d 

samplejocator 

set_pick_window 

spline_curve 
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spline_curve2d 

surface.model 

text.alignment 

text_orientation2d 

transform.points 

vdc.extent 

view.camera 

view.port 

viewpoint 

Integer Only 

file.tojntbitmap 

intbitmap.print 

intblock.write 

intcircle 

intconcat_transform2d 

intecho_update2d 

intline_repeat_length 

intpartial.arc 

intperimeter_repeat_length 

intpolymarker2d 

intrectangle 

intsample_locator2d 

inttext_orientation2d 

intview_matrix2d 


spline_curve3d 

text2d 

text_line_path 

text_orientation3d 

u_knot_vector 

vdc_to.dc 

view_matrix2d 

view.volume 

wc_to_vdc 

intarc 

intblock.move 

intcharacter.height 

intclip.rectangle 

intdraw2d 

intinquire_pick_window 

intmarker.size 

intpartiaLcircle 

intpolygon2d 

intpop_matrix2d 

intreplace_matrix2d 

intset_pick_window 

inttransform_point2d 

intview.port 


spline.surface 

text3d 

textjine.space 

transform.point 

v_knot_vector 

vdc_to_wc 

view_matrix3d 

view.window 

zbuffer.switch 

intbitmap_to_file 

intblock.read 

intcharacter .width 

intconcat_matrix2d 

intecho_type2d 

intinquire_text_extent2d 

intmove2d 

intpartial_polygon2d 

intpolyline2d 

intpush_matrix2d 

intrequest_locator2d 

inttext2d 

intvdc.extent 

intview.window 
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Device Coordinate Only 


dcbitmap_to_file 

dcblock.read 

dccharacter.width 

dcecho_update 

dcpartiaLpolygon 

depolymarker 

file_to_dcbitmap 


debitmap.print 

dcblock_write 

dedraw 

dcmarker.size 

depolygon 

dcrectangle 


Common to Floating Point and Integer 


character_expansion_factor 

curve.resolution 

intra_character_space 

set_hit_mode 

text_precision 


character.slant 

flush.matrices 

pop_matrix 

set_pl_p2 

vdc justification 


dcblock.move 

dccharacter.height 

dcecho.type 

demove 

depolyline 

detext 


clip.indicator 

inquire.hit 

push_vdc_matrix 

text_path 
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Common to All Systems 


await.event 

background.color.index 

clear.control 

define.color.table 

disablements 

drawing.mode 

filLcolor 

gclose 

gerr.procedure 

initiate.request 

inquire.fb.configuration 

inquire.input.capabilities 

interior.style 

line.type 

marker.color 

perimeter.color 

read.choice.event 

set.signals 

text.font.index 

track.off 


await.retrace 

bank.switch 

clear_view_surface 

defme_raster_echo 

display .enable 

enable.events 

fill.colorjndex 

gerr.message 

gescape 

inquire.choice 

fnquire.gerror 

inquire_request_status 

line.color 

make.picture.current 

marker_color_index 

perimeter_color_index 

request.choice 

text.color 

text.switching.mode 

vertex.format 


background.color 

buffer.mode 

dbuffer.switch 

designate.character.set 

double.buffer 

file.print 

filLdither 

gerr.print.control 

gopen 

inquire.color.table 

inquire.id 

inquire.sizes 

line.color.index 

mapping.mode 

marker.type 

perimeter.type 

sample.choice 

text.color.index 

track 

write.enable 
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